[Please view this TXT in monospaced font :)]

[This Text is in Spanish. If you consider that is a good text for learning
MSX-BASIC and you want to translate, contact to me please for help you]

ESCAPE FORM DWARVES' GOLDMINE
-----------------------------
by ThePetsMode (Oct-2009)
Molins de Rei - Barcelona - Spain

Code&GFX&Sound: JamQue (Rafel Prez)
Level Designer: Atreyu (Angel Hidalgo)
Testing&Ideas: Napalm (Arnau Castellvi)

Music Score Inspiration from:
  mineralminer.mod by okeanos from modarchive.org
  eagle_no_-_sunrise.mod by [Anonimous] from modarchive.org

GFX Creator : 
  nMSXtiles v0.3 & Photoshop

Contact:
www.thepetsmode.com
jamque@thepetsmode.com

---------------------------------------------------------------------------

HISTORIA
--------
Hans, el despistado clerigo se ha caido mientras paseaba por el monte dentro
de las abandonadas y antiguas minas de oro de los Enanos del Norte.
Ayuda a Hans a salir de estas minas laberinticas antes de que se acabe el 
aire respirable y cuidado con las rocas que se desprenden.
Hans ha pensado que un mapa podria ser util para poder salir de las minas,
pero Hans no tiene muy buena memoria y su orientacin es ms bien poca.
As que no se acuerda muy bien por donde ha pasado.
Cada nivel de las minas est cerrado con llave. Tipico de los Enanos del 
Norte, cerrar con llave y dejarla por ah tiranda dentro. Te va a tocar
buscarlas para poder avanzar.
No, Hans no dispara ni salta...que esto es MSXBASIC!.
Y tampoco tiene un medalln repele muertos vivientes, tampoco le hace falta.
Llegar Hans a casa a tiempo de cenar?

COMO JUGAR
----------
Se trata de un juego de laberintos. Guia a Hans con los cursores o 
el Joystick 1. 
Tienes un tiempo limitado para encontrar la llave y la salida del nivel. 
Cuando Hans tenga poco aire, se pondr morado. 
Quedarte sin aire supone reempezar el nivel.
Tienes 14 niveles que completar. 
Las rocas que caen del techo restan tiempo/aire. Mejor no te toquen.
Vale la pena llegar a completar los 14 niveles?
S. El juego tiene un final argumental ;)

-------------------------------------------------------------
ESCAPE FORM DWARVES' GOLDMINE  OFFICIAL GUIDE (cooming soon)
With Maps and Cheats :)
-------------------------------------------------------------

---------------------------------------------------------------------------

Este texto explica el funcionamiento del juego programado en Basic.
Pretende ser un texto para ayudar a entender como se ha hecho y
que otros puedan aprender de la programacin de este juego.

Voy a ir por segmentos del codigo y lo comento un poco.

10-70 
Presentacin en modo texto y anuncio de que se va a tardar en cargar
los graficos. Esta carga es muy lenta dado que el MSXBASIC ha de subir byte
a byte los DATA a la VRAM con VPOKES.

80-130
Inicializacin de modo grafico y variables (ver apendice A)
Se definen 3 llamadas a Rutinas de BIOS
DEFUSR1=&H41 -> Apaga la pantalla (util cuando estamos dibujando)
DEFUSR2=&H44 -> Enciende la pantalla (y aparece el dibujo de golpe)
DEFUSR3=&H90 -> Borra el buffer de PLAY y apaga el PSG de sonido
Se definen con las instrucciones BASE cuales son las posiciones de VRAM
donde escribir para subir los graficos (ver apendice A).

140-150
Llamadas a subrutinas : 
Linea 4310: Vaciado de pantalla, Carga de VRAM, Muestra la Intro del juego y pinta la
pantalla de juego.
Linea 4270: Actualiza el marcador de puntos.
Linea 4830: Actualiza la barra de aire.
Linea 450: Inicializacin de las variables del nivel (ver apendice B)
Linea 690: Generador del nivel

160
Inicializacion de las variable de habitacion.

170-180
Inicializacion de las rutinas de interrupcion. Se utilizan dos:
INTERVAL que ocurrira cada 180 milisegundos (9). Salta a 1510.
SPRITE que ocurrira cada vez que se solapen los Sprites. Salta a 1740.

190
Llamada a subrutina:
Linea 3980: Pinta la primera habitacion del juego

200-440
Bucle principal del juego. En el se controla la lectura de los cursores y 
el joystick 1. Se evalua la direccion, se actualiza la posicion de Hans, 
se evalua si ha de cambiar de pantalla al llegar a los extremos y en caso
afirmativo procede a dibujar la siguiente habitacion. Tambien se controla
si se han de activar las rocas en la habitacion actual (RO=0 o RO=1, linea
400)

Detalle: Para saber si ha de cambiar de habitacion hay que controlar 
el valor de varias variables simultaneamente mediante IF y ANDs. Pero 
dado que el MSXBASIC no verifica si se ha de ejecutar la rutina de INTERVAL
hasta que finaliza la interpretacion de una linea de codigo, se ha tenido
que separar estas condicines en dos partes. Se evalua solo una variable y 
si esta es cierta se evalua el resto. Sino se hace as, el movimiento de 
Hans no es fluido y la rutina no salta correctamente a tiempo. (Ver lineas
de la 320 a 380).

450-680 (subrutina)
Inicializacin de las variables del nivel.
Actualizacion del marcador LEVEL (Lineas 510-520)
(ver apendice B)

690-1110(subrutina)
Generador del nivel
Se genera una matriz en DU de 64 casillas. Cada casilla es un habitacion
del laberinto que contiene que salidas tiene, si est aqu la llave, la 
entrada o la salida de esta a nivel de bit.

1120-1420(subprograma)
Final del juego.
No puedo decir nada ms ;)

1430-1500(subrutina)
Subrutina INTERVAL utilizada durante el final del juego.
Controla la musica.

1510-1730(subrutina)
Subrutina INTERVAL.
Se ha programado su ejecucion cada 180 milisegundos.
Aqu se controla los cambios en la msica, la disminicin del Aire que en 
caso necesario se repinta llamando a la linea 4830 o si ha llegado a cero
anunciar la muerte de Hans y reempezar el nivel.
Esta es la rutina que pinta a Hans en pantalla. Si MSXBASIC fuera ms 
rapido a esta rutina se la llamaria cada 1/50 segundos y el juego iria 
sincronizado con la interrupcion VSYNC, pero...MSXBASIC es leeeento ;)

1740-1950(subrutina)
Subrutina SPRITE.
Se activa al detectar la solapacin de 2 sprites (figuras moviles).
Aqui se controla si se coje la llave, si se ha llegado a la salida y hay que
cambiar de nivel, si una roca le ha dado a Hans, se actualiza la varible de
puntos (SC) y se verifica si se ha llegado al final del juego

1960-2040(subrutina)
Subrutina de muerte de Hans.
La llama la rutina de INTERVAL

Detalle: Aqui hay una pirueta para no escribir ms codigo y as ahorrar
memoria. Cuando se determina en la linea 1610 que Hans est muerto, se
salta a la 1960 para que lo notifique al jugador, se actualiza el marcador
de puntos, el de aire,...PERO se vuelve del INTERVAL GOSUB por la rutina
de SPRITE (ver linea 2030). Esto es as porque al morir o cambiar de nivel
hay que hacer los mismos cambios :) y el RETURN de la rutina de SPRITE
(linea 1950), MSXBASIC lo toma como retorno de la rutina de INTERVAL.

2050-2280(Datos)
Numeros de Tiles (celdas graficas) para generar cada parte de la pantalla
de juego.
Estos DATA estan en decimal dado que queremos que se pinten rapidamente
en pantalla y no entretenemos al bucle que las lee en hacer conversiones.

Detalle: Varias comas (,) seguidas en la instruccion DATA, MSXBASIC lo 
interpreta como un 0. Es decir :
DATA 45,34,0,0,23 = DATA 45,34,,,23
Y as me ahorro unos bytes de RAM.

2290-2310(Datos)
Tiles de los textos LEVEL, SCORE y AIR
Estos DATA estan en Hexadecimal sin necesidad del &H dado que los leemos
como cadena de texto (Z$) y los convertimos a numeros con la 
instruccion VAL.

2320-3340(Datos)
Forma de los Tiles. Patrones.
Estos DATA estan en Hexadecimal sin necesidad del &H dado que los leemos
como cadena de texto (Z$) y los convertimos a numeros con la 
instruccion VAL.

3410-3500(Datos)
Color de los Tiles.
Estos DATA estan en Hexadecimal sin necesidad del &H dado que los leemos
como cadena de texto (Z$) y los convertimos a numeros con la 
instruccion VAL.

Detalle: Dado que los datos de los colores en este juego son muy repetidos
y seguidos, estn comprimidos con un metodo sencillo de cuantos colores
van seguidos. Lo que conoce como compresion RLE.
(http://es.wikipedia.org/wiki/RLE)

3510-3530(Datos)
Valores para generar el nivel que nos dan numeros pseudoaleatorios.

3540-3820(Datos)
Forma de los Sprites (ver Apendice C)

3830-3970(Datos)
Semillas de los niveles.
Cada nivel esta codificado en 6 bytes y la rutina generadora de niveles
(linea 690) usa estos valores. El juego tiene 14 niveles, pero podria tener
muchisimos ms. A ms RAM ms niveles. Tal y como est el codigo ahora y
teniendo en cuanta la RAM que hay que dejar libre para que MSXBASIC pueda
funcionar, se podria llegar a tener ms de 60 niveles de juego.

3980-4260(subrutina)
Pinta la habitacion actual del nivel.
Para hacerlo ms rapidamente, solo pinta las secciones que son diferentes
en relacin a la anterior habitacion pisada. As no se realizan tantas
escrituras a VRAM si los datos que queremos para mostrar la habitacin ya
estn ah.
Tambien se actualiza el mapa, pero se borra parte del recorrido, dado que
Hans es algo despistado y no se acuerda muy bien de por donde iba ;).
Finalmente se situan los SPRITES de entradas, llave o salida si estamos
en esas habitacines.

4270-4290(subrutina)
Actualiza el marcador de puntos.

4300-4560(subrutina)
Vaciado de pantalla, Carga de VRAM, Muestra la Intro del juego y pinta la
pantalla de juego.

4570-4820(subrutina)
Sube a VRAM los datos graficos.
Como esto es muy largo y MSXBASIC lo hace muy lentamente, para informar
al jugador que no se ha bloqueado el juego ni el MSX, se va cambiado los
colores de los bordes con COLOR,,X. Esto recuerda a las antiguas cargas en
casete de los juegos. Es algo epileptico pero nostalgico.

4830-4940(subrutina)
Actualiza la barra de aire.
En caso de que le quede poco, se cambia el color de la cara de Hans.

4950-4980(subrutina)
Pinta los Tiles para indicar que hay salida al Sur

4990-5030(subrutina)
Pinta los Tiles de la seccion Este, Norte o Oeste de la habitacion.

5040-5070(subrutina)
Pinta los Tiles que sirven para mostrar que en la siguiente habitacion
hacia el norte hay una pared. Un detalle chulo ;)

5080-5090(subrutina)
Pinta en negro los tiles que muestran que en la siguiente habitacion
hacia el norte hay una pared para indicar que el pasillo hacia el norte
es ms largo que dos habitaciones.

5100-5120(subrutina)
Pinta en negro los tiles para indicar que no hay salida al Sur

5130-5250(subrutina)
Pequea animacin - Intro del juego :)

---------------------------------------------------------------------------

Apendice A : Variables de juego
-------------------------------
BS=BASE(10)    : Direccion Inicial de VRAM Pantalla (Tiles)
BC=BASE(11)    : Direccion Inicial de VRAM Colores
BP=BASE(12)    : Direccion Inicial de VRAM Patrones
LF=15          : [Life] Vida/aire para marcador
AI=2250        : Aire
SC=0           : [Score] Puntuacion 
XX=140         : Posicion X de Hans
YY=75          : Posicion Y de Hans
RN=PS(3)       : [Room Number] Habitacion actual
NR=DU(RN)AND15 : Direcciones abiertas de la habitacion RN
OL             : [Old Room] Anterior Habitacion
LV=1           : [Level] Nivel Actual
XI             : Limite Izquierdo-Oeste de XX 16 o 64
XD             : Limite Derecho-Este de XX 96 o 144
YS             : Limite Sur 78 o 86
KY             : [Key] Llave a 1 la tengo a 0 no la tengo
MA$            : Music Channel A
MB$            : Music Channel B
MC$            : Music Channel C
MX             : [Mixer] (Sound 7)
IT             : [Interrupt Sprites] Dibujo Sprites en INTERVAL Si/No
YR             : Posicion Y de Roca
XR             : Posicion X de Roca
RO             : Roca Off/On (0/1)
SE             : Sprite Num [HAT]  Sombrero Valores:0-4-08-12
SA             : Sprite Num [HAIR] Barba    Valores:1-5-09-13
SF             : Sprite Num [FACE] Cara     Valores:2-6-10-14
SB             : Sprite Num [BODY] Cuerpo   Valores:3-7-11-15
                                            (Drch-Izq-Up-Dwn)
OM(3)          : [Old Map] Casillas de Mapa Pisadas
CC             : Color de Cara (9 o 13)

Apendice B : Variables del generador de laberintos
--------------------------------------------------
AM=8           : Medida del Laberinto
DU(AM*AM)      : Matriz del Laberinto
PS(6)          : Valores Semilla
ST(AM*AM)      : Temporal al generar para control
ME(64)         : Matriz de pseudoaleatoriedad del Laberinto

Apendice C : Numeros de Sprites
-------------------------------
Num - Nombre (Color)

00 - Sobrero Hans Drch (14)
01 - Barba Hans Drch (10)
02 - Cabeza Hans Drch (9)
03 - Cuerpo Hans Drch (14)
04 - Sobrero Hans Izq (14)
05 - Barba Hans Izq (10)
06 - Cabeza Hans Izq (9)
07 - Cuerpo Hans Izq (14)
08 - Sobrero Hans Up (14)
09 - Barba Hans Up (10)
10 - Cabeza Hans Up (9)
11 - Cuerpo Hans Up (14)
12 - Entrada Suelo IZQ (1)
13 - Entrada Suelo DRC (1)
14 - Sobrero Hans Dwn (14)
15 - Barba Hans Dwn (10)
16 - Cabeza Hans Dwn (9)
17 - Cuerpo Hans Dwn (14)
18 - Punto Gris del Mapa (14)
19 - Llave (11)
20 - Tapa Salida Techo IZQ (1)
21 - Tapa Salida Techo IZQ Interior (14)
22 - Tapa Salida Techo DRC (1)
23 - Tapa Salida Techo DRC Interior (14)
24 - Salida Techo IZQ (1)
25 - Salida Techo DRC (1)
26 - Cuerda (11)
27 - Roca (9)